home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / u_man / cat1 / htsmall.z / htsmall
Text File  |  1998-10-30  |  12KB  |  331 lines
  1.  
  2.  
  3.  
  4. HHHHTTTTSSSSMMMMAAAALLLLLLLL((((1111))))                                                          HHHHTTTTSSSSMMMMAAAALLLLLLLL((((1111))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      htsmall - create an index for a web site from a data definition
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ////uuuussssrrrr////WWWWeeeebbbbFFFFaaaacccceeee////bbbbiiiinnnn////hhhhttttssssmmmmaaaallllllll [-_x] [-_p _p_e_r_m_i_s_s_i_o_n_s] [-_m _m_a_t_c_h] [_s_o_u_r_c_e]
  13.      destinition
  14.  
  15. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  16.      _h_t_s_m_a_l_l is a simple "web site compiler."  It provides a subset of the
  17.      functionality found in the _h_t_m_a_k_e site compiler (_s_e_e _h_t_m_a_k_e(_1)).  _h_t_s_m_a_l_l
  18.      reads a source directory (the current working directory if not specified
  19.      on the command line) and generates a single page in the destination
  20.      directory.  htsmall also copies all necessary files within the source
  21.      directory to the destination directory.
  22.  
  23.      The generated page is a simple index, useful for the top level of a web
  24.      site.  The index is structured as a table, with one index entry per row.
  25.  
  26.      __R_o_w _S_t_r_u_c_t_u_r_e_ Each row contains a combination of the following (from
  27.      left to right)
  28.  
  29.           {<Graphic> or <Label>} <Description>
  30.  
  31.      Graphic:
  32.           a "gif" image, usually an icon.  This is placed at the leftmost edge
  33.           of the row.
  34.  
  35.      Label:
  36.           the label is a short description of what the link does.  In lieu of
  37.           a graphic, the label is displayed.
  38.  
  39.      Description:
  40.           a [detailed] description.  This can be of any length, lines are
  41.           wrapped to the right of the graphic and label.
  42.           All row components are part of a single, large hotlink (one per
  43.           row), which points a category file (described below).
  44.           __R_o_w _S_p_e_c_i_f_i_c_a_t_i_o_n_ When _h_t_s_m_a_l_l is invoked, it searches the source
  45.           directory for files with ".cgi", ".html" and ".shtml" extensions
  46.           having names prefixed (having as their first few characters) with a
  47.           usr-specifiable `match' value (e.g., "Tasks.").
  48.           By default, this match value is equivalent to the name of the source
  49.           directory although you can specify a different value by using the -m
  50.           switch (see options).
  51.  
  52.      Example: if htsmall was invoked like
  53.  
  54.           htsmall -m Applications /usr/people/bob/mysource /var/www/htdocs
  55.  
  56.      then the following files would fit htsmall's search criteria:
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. HHHHTTTTSSSSMMMMAAAALLLLLLLL((((1111))))                                                          HHHHTTTTSSSSMMMMAAAALLLLLLLL((((1111))))
  71.  
  72.  
  73.  
  74.           Applications.test.html
  75.           Applications.artwork.cgi
  76.           Applications.brian.demo.shtml
  77.  
  78.      Note: it is illegal to have two or more files with the same name but
  79.      different extensions and htsmall will report this as an error:
  80.  
  81.           Applications.brian.demo.shtml
  82.           Applications.brian.demo.cgi
  83.  
  84.      The foregoing is illegal.
  85.  
  86.      Each matching file, which will hereafter be referred to as "category"
  87.      files, becomes a separate row in htsmall's generated index page.  Each
  88.      row is a single hotlink (graphic, label and description).  The link
  89.      points to the category file ([S]HTML page or CGI script) for which the
  90.      row was created.
  91.  
  92.      For each category file, htsmall looks for two files, one a "gif" file
  93.      containing the graphic (icon) icon to be used for the row (see above),
  94.      and a separate "label" file.
  95.  
  96.      For both the gif and label files, the file name is the same as the
  97.      category file's name without the match value (such as "Applications" in
  98.      our above example.  For the gif file, the extension must be `.gif' while
  99.      the label file's extension is `.lbl'.
  100.  
  101.      Thus, the label and gif files for "Applications.artwork.cgi" (assuming
  102.      the match value was "Applications") would be:
  103.  
  104.           `artwork.lbl'  and  `artwork.gif'
  105.  
  106.      respectively.
  107.  
  108.      The label file is used for two purposes: the first line of the file can
  109.      contain a string to be used as a label if no graphic is found for the
  110.      matching category file (the label will also be displayed if the user
  111.      turns off image loading, via the <IMG> tag's ALT="" attribute).
  112.  
  113.      The remaining lines of the file contain the text of the description (see
  114.      _Row Structure_, above).  There can be as many lines as you like and they
  115.      can contain any HTML tags (including server side includes) you like.
  116.      Note that the entire description text will be hot (linked) and that
  117.      carriage returns ending lines will be parsed by the browser as whitespace
  118.      (according to HTML parsing rules which reduce any number of consecutive
  119.      whitespace characters to single spaces).
  120.  
  121.      __B_a_c_k_g_r_o_u_n_d_ You can add a tiled background (for display by Netscape-
  122.      compatible browsers) to the page by placing a `background.gif' image in
  123.      the source directory.  htsmall will detect the presence of the background
  124.      file and automatically modify the page's <BODY> tag to account for the
  125.      background attribute.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. HHHHTTTTSSSSMMMMAAAALLLLLLLL((((1111))))                                                          HHHHTTTTSSSSMMMMAAAALLLLLLLL((((1111))))
  137.  
  138.  
  139.  
  140.      __B_a_n_n_e_r _I_m_a_g_e_ A banner image may be placed at the very top of the page
  141.      by including a `banner.gif' image within the source directory.  No other
  142.      name is allowed.
  143.  
  144.      If you are using Netscape Navigator 2.0 or later, or another browser
  145.      which supports Netscape-style client-side image maps, you may have an
  146.      image map built into the page by creating a `banner.map' file within the
  147.      source directory.
  148.  
  149.      The map file should contain only <AREA> tags (no <MAP> ... </MAP>).
  150.  
  151.      _h_t_s_m_a_l_l will detect the presence of the map file and automatically
  152.      generate the appropriate enclosing tags (<MAP> and <NOMAP>) and
  153.      incorporate the map file's contents into the page.
  154.  
  155.      __I_n_c_l_u_d_e_s _a_n_d _E_x_e_c_s_ You can have _h_t_s_m_a_l_l include text before and after
  156.      the banner image (if present), after each index row, and at the bottom of
  157.      the page. To do this, create one or more of the following files:  (as
  158.      befits your needs)
  159.  
  160.      upper.inc
  161.           Text to be placed before banner graphic.  Text will span entire
  162.           page.
  163.  
  164.      middle.inc
  165.           Text to be placed after banner graphic but before index rows. Text
  166.           will span entire page.
  167.  
  168.      between.inc
  169.           Text to be placed immediately after banner graphic (will not be hot
  170.           [linked]).  Text will wrap underneath descriptions (to the right of
  171.           the graphic or label).
  172.  
  173.      lower.inc
  174.           Text to be placed after all index rows.  Text will span entire page.
  175.  
  176.      You can also include text specific to each row by creating a `.inc' file
  177.      having the same name as the category file without the match value
  178.      ("Applications" in the above examples).  Thus, the include for
  179.      "Applications.artwork.cgi" (assuming the match value was "Applications")
  180.      would be:
  181.  
  182.                          `artwork.inc'
  183.  
  184.      Each `.inc'lude file can contain any number of lines.  Text will be
  185.      parsed according to HTML rules (as with descriptions, described above).
  186.  
  187.      If your web server supports and has enabled "server side includes" (which
  188.      are beyond the scope of this document), you can have htsmall invoke a cgi
  189.      script before and after the banner image (if present), after each index
  190.      row, and at the bottom of the page.  The results (output text) of these
  191.      scripts will be written into the page as it is sent to the browser.  Note
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. HHHHTTTTSSSSMMMMAAAALLLLLLLL((((1111))))                                                          HHHHTTTTSSSSMMMMAAAALLLLLLLL((((1111))))
  203.  
  204.  
  205.  
  206.      that because these scripts will be outputting text into the middle of an
  207.      existing HTML page, they should not generate any the following tags:
  208.                <HTML>   <HEAD>   <TITLE>   </TITLE>
  209.                </HEAD>   <BODY>   </BODY>   </HTML>
  210.  
  211.      Specifying which script to run is similar to that for specifying include
  212.      files, the principal difference is the extension:
  213.  
  214.      upper.xeq
  215.           Script will be executed before banner graphic.  Output text will
  216.           span entire page.
  217.  
  218.      middle.xeq
  219.           Script will be executed after banner graphic but before index rows.
  220.           Output text will span entire page.
  221.  
  222.      between.xeq
  223.           Script will be executed immediate after row's description.  Output
  224.           text will wrap underneath descriptions (to the right of the graphic
  225.           or label).
  226.  
  227.      lower.xeq
  228.           Script will be executed after all rows have been displayed.  Output
  229.           text will span the entire page.
  230.  
  231.      You can also have executed a script specific to each row by creating a
  232.      `.inc' file having the same name as the category file without the match
  233.      value ("Applications"in the above examples).  Thus, the include for
  234.      "Applications.artwork.cgi" (assuming the match value was "Applications")
  235.      would be:
  236.  
  237.           `artwork.xeq'
  238.  
  239.      Note: _h_t_s_m_a_l_l will automatically copy files with `.xeq' to the
  240.      destination directory, changing their extensions to `.cgi'.
  241.  
  242. OOOOPPPPTTTTIIIIOOOONNNNSSSS
  243.      _----_xxxx   suppress use of labels if graphics are not present.
  244.  
  245.      _----_mmmm   match_value Specifies the string (other than the name of the source
  246.           directory) against which to match category files.  The generated
  247.           page contains one index row for each category file.
  248.  
  249.      _----_pppp   permissions mail {`u', `o', `g'} Any combination of `u', `o' and `g'
  250.           can be used (but no letter more than once).  The letters can be
  251.           either upper or lowercase.  Specify base access permissions for the
  252.           generated page and any related (copied) files.  Only the user is
  253.           ever given write permission on the page.  Group and Other users are
  254.           given read or execute access as is appropriate.
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. HHHHTTTTSSSSMMMMAAAALLLLLLLL((((1111))))                                                          HHHHTTTTSSSSMMMMAAAALLLLLLLL((((1111))))
  269.  
  270.  
  271.  
  272. CCCCAAAAVVVVEEEEAAAATTTTSSSS
  273.      Beware of using large icons, long labels or descriptions.  These can
  274.      crowd rows, resulting in illegibility, or result in very long pages.
  275.  
  276. BBBBUUUUGGGGSSSS
  277.      There are a couple of unsupported switches that are remnants of htsmall's
  278.      parentage (being derived from htmake).  It is expected that they'll be
  279.      removed in a future release.
  280.  
  281. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  282.      htmake(1)
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.